<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML VERSION="2.0">
<HEAD>
<TITLE>Command-line Usage</TITLE>
</HEAD>
<BODY BGCOLOR=white>
<A NAME="top"></A>
<H1 ALIGN=CENTER>Command-line Invocation</H1>
<HR>
All Graphviz programs have a similar invocation:<BR>
<TABLE><TR><TD>
<CODE><I>cmd</I> [ <I>flags</I> ] [ <I>input files</I> ]<CODE>
</TR></TABLE>
If no input files are supplied, the program reads from <STRONG>stdin</STRONG>.
<H3>Flags</H3>
<DL>
<DT><STRONG>-G</STRONG><I>name</I>[=<I>value</I>]
<DD>Set a graph attribute, with default <I>value</I> = <TT>true</TT>.
<DT><STRONG>-N</STRONG><I>name</I>[=<I>value</I>]
<DD>Set a default node attribute, with default <I>value</I> = <TT>true</TT>.
<DT><STRONG>-E</STRONG><I>name</I>[=<I>value</I>]
<DD>Set a default edge attribute, with default <I>value</I> = <TT>true</TT>.
<DT><A NAME=minusK><STRONG>-K</STRONG></A><I>layout</I>
<DD>Specifies which default layout algorithm to use, overriding the default from the command name. For example, running
<TT>dot -Kneato</TT> is equivalent to running <TT>neato</TT>.
<DT><A NAME=d:T><STRONG>-T</STRONG></A><I>format</I>[:<I>renderer</I>[:<I>formatter</I>]]       
<DD>Set output language to one of the <A HREF=output.html>supported formats</A>.
By default, <A HREF=output.html#d:dot>attributed dot</A> is produced.
<P>
Depending on how Graphviz was built, there may be multiple renderers for
generating a particular output format, and multiple formatters for 
creating the final output. For example, a typical installation
can produce <A HREF="output.html#d:png">PNG</A>
output using either the Cairo or GD library. The desired rendering engine
can be specified after a colon. If there are multiple formatting engines
available, the desired one can be specified in a similar fashion after
the rendering engine. Thus, <TT>-Tpng:cairo</TT> specifies PNG
output produced by Cairo (using the Cairo's default formatter), and 
<TT>-Tpng:cairo:gd</TT> specifies PNG
output produced by Cairo formatted using the GD library.
<P>
If no renderer is specified, or a renderer but no formatter, the default one
is invoked. The flag <TT>-T<I>format</I>:</TT> produces a list of all
of the renderers available for the specified <I>format</I>, the first one
listed with a prefix matching <I>format</I> being the default.
Using the <TT>-v</TT> flag, described below, will print which format,
renderer, and formatter are actually used.
<DT><STRONG>-V</STRONG>             
<DD>Emit version information and exit.
<DT><STRONG>-l</STRONG><I>library</I>
<DD>User-supplied, device-dependent library text. Multiple flags may
be given. These strings are passed to the code generator at the
beginning of output. 
<P>For PostScript output, they are treated as file names
whose content will be included in the preamble after the standard preamble.
If <I>library</I> is the empty string <TT>""</TT>, the standard preamble
is not emitted.
<DT><A NAME=d:n><STRONG>-n</STRONG>[<I>num</I>]</A>      
<DD>Sets no-op flag in <STRONG>neato</STRONG>. 
If set, <STRONG>neato</STRONG> assumes nodes have already been 
positioned and all nodes have a <A HREF=attrs.html#d:pos>pos</A>
attribute giving
the positions. It then performs an optional adjustment to remove node-node
overlap, depending on the value of the 
<A HREF=attrs.html#d:overlap>overlap</A> attribute, computes the edge 
layouts, depending on the value of the 
<A HREF=attrs.html#d:splines>splines</A> attribute, and
emits the graph in the appropriate format. If <I>num</I> is supplied,
the following actions occur:
<DL>
<DT><I>num</I> = 1
<DD>Equivalent to <STRONG>-n</STRONG>.
<DT><I>num</I> > 1
<DD>Use node positions as specified, with no adjustment to
remove node-node overlaps, and use any edge layouts already specified
by the <A HREF=attrs.html#d:pos>pos</A> attribute. <STRONG>neato</STRONG>
computes an edge layout for any edge that does not have a <B>pos</B> attribute.
As usual, edge layout is guided by the 
<A HREF=attrs.html#d:splines>splines</A> attribute.
</DL>
<DT><STRONG>-o</STRONG><I>outfile</I>    
<DD>Write output to file <I>outfile</I>. By default, output goes to
<STRONG>stdout</STRONG>.
<DT><STRONG>-O</STRONG>
<DD>Automatically generate output file names based on the input
file name and the various output formats specified by the <STRONG>-T</STRONG>
flags.
<DT><STRONG>-P</STRONG>
<DD>Automatically generate a graph that shows the plugin configuration of
the current executable.   e.g.  <STRONG>dot -P -Tps | lpr</STRONG>
<DT><STRONG>-q</STRONG>
<DD>Suppress warning messages.
<DT><A NAME=d:s><STRONG>-s</STRONG></A>[<I>scale</I>]
<DD>Set input scale to <I>scale</I>. If this value is omitted,
72.0 is used. This number is used to convert the point coordinate
units used in the <A HREF=attrs.html#d:pos>pos</A> attribute 
into inches, which is what is expected by neato and fdp. 
Thus, feeding the output of a graph laid out by one program into
neato or fdp almost always requires this flag.
Ignored if the <STRONG>-n</STRONG> flag is used.
<DT><STRONG>-v</STRONG>             
<DD>Verbose mode
<DT><STRONG>-x</STRONG>             
<DD>In <STRONG>neato</STRONG>, on input, prune isolated nodes and peninsulas.
This removes uninteresting graph structure and produces a less cluttered
drawing.
<DT><STRONG>-y</STRONG>             
<DD>By default, the coordinate system used in generic output formats, 
such as <A HREF=output.html#d:dot>attributed dot</A>,
<A HREF=output.html#d:xdot>extended dot</A>,
<A HREF=output.html#d:plain>plain</A> and
<A HREF=output.html#d:plain-ext>plain-ext</A>,
is the standard cartesian system with the origin in the lower left corner, 
and with increasing y coordinates as points move from bottom to top.
If the <CODE>-y</CODE> flag is used, the coordinate system is inverted,
so that increasing values of y correspond to movement from top to bottom.
<DT><STRONG>-?</STRONG>             
<DD>Print usage information, then exit.
</DL>
If multiple <STRONG>-T</STRONG> flags are given, drawings of the graph
are emitted in each of the specified formats. Multiple <STRONG>-o</STRONG>
flags can be used to specify the output file for each format. If there
are more formats than files, the remaining formats are written to
<STRONG>stdout</STRONG>.
<P>
Note that the <STRONG>-G</STRONG>, 
<STRONG>-N</STRONG> and
<STRONG>-E</STRONG> flags override any initial attribute declarations
in the input graph,
i.e., those attribute statements appearing before any node, edge or
subgraph definitions.
In addition, these flags cause the related attributes to be permanently
attached to the graph. Thus, if attributed dot is used for
output, the graph will have these attributes.
<H3>Environment Variables</H3>
<DL>
<DT><STRONG>GDFONTPATH</STRONG>
<DD>
List of pathnames giving directories which a program should search for fonts.
Overridden by <A HREF=#d:DOTFONTPATH>DOTFONTPATH</A>.
<I>Used only if Graphviz is not built with the <TT>fontconfig</TT> library</I>
<DT><A NAME=d:DOTFONTPATH><STRONG>DOTFONTPATH</STRONG></A>
<DD>
List of pathnames giving directories which a program should search for fonts.
Overridden by <A HREF=attrs.html#d:fontpath><STRONG>fontpath</STRONG></A>.
<I>Used only if Graphviz is not built with the <TT>fontconfig</TT> library</I>
<DT><A NAME=d:SERVER_NAME><STRONG>SERVER_NAME</STRONG></A>
<DD>
If defined, this indicates that the software is running as a web application,
which restricts access to image files. See 
<A HREF=#d:GV_FILE_PATH>GV_FILE_PATH</A>.
<DT><A NAME=d:GV_FILE_PATH><STRONG>GV_FILE_PATH</STRONG></A>
<DD>
If <A HREF=#d:SERVER_NAME>SERVER_NAME</A> is defined, image files are
restricted to exist in one of the directories specified by <TT>GV_FILE_PATH</TT>.
This last is a list of directory pathnames, separated by semicolons in Windows or
by colons otherwise.
Note that sometimes, when using one of the layout programs in a web
script, it is not enough to use an export command but rather the
variables should be set when the command is run, for example,<BR>
<CODE>
SERVER_NAME=xxx GV_FILE_PATH="images:etc/images:/usr/share/images" dot -Tpng -o x.png x.gv
</CODE>
<P>
Note that the image files must really reside in one of the specified directories. If the
image file is specified as an absolute or relative pathname, a warning is given and only
the base name is used.
<DT><A NAME=d:GVBINDIR><STRONG>GVBINDIR</STRONG></A>
<DD>
Indicates which directory contains the Graphviz config file and
plug-in libraries. If it is defined, the value overrides any other
mechanism for finding this directory. If Graphviz is properly installed,
it should not be needed, though it can be useful for relocation on
platforms not running Linux or Windows.
</DL>
</BODY>
</HTML>
